<?php
/**
 * Abstract class for plugins type of <i>Psa_Plugin_Before_Group_Create</i>.
 * 
 * LICENSE:
 * 
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with This library. If not, see <{@link http://www.gnu.org/licenses/}>.
 *
 * @link http://code.google.com/p/phpstartapp/
 * @author Bojan Mauser <bmauser@gmail.com>
 * @copyright Bojan Mauser 2009
 * @package psa
 * @subpackage plugins
 * @version $Id: Psa_Plugin_Before_Group_Create.class.php 112 2008-09-14 00:03:56Z bmauser $
 */


/**
 * Abstract class for plugins type of <i>Psa_Plugin_Before_Group_Create</i>.
 * You can start new group creation process by passing '<kbd>new</kbd>' to {@link Psa_Group} class constructor. See 
 * {@link Psa_Group::__construct() constructor} method of {@link Psa_Group} class.
 * 
 * Before a new group is successfully created with {@link Psa_Group::save() save()} method of the {@link Psa_Group} object, 
 * {@link psa_main()} method of the plugin object that extends this class will be called.
 * You can write <i>Psa_Plugin_Before_Group_Create</i> plugins by extending this class. Here is an example:
 * 
 * <code>
 * <?php
 * class my_plugin extends Psa_Plugin_Before_Group_Create{
 * 	
 * 	// you have to define psa_main() method in your child class
 * 	function psa_main($group){
 * 		
 * 		// set some property to new group
 * 		$group->good_students = 'yes';
 * 		// you can put here any logic you need
 * 	}
 * }
 * ?>
 * </code>
 * 
 * When this example plugin is registered every new created group will have property called
 * <kbd>good_students</kbd> with value '<kbd>yes</kbd>'.
 * 
 * <b>Note:</b> this plugin is called before the new group is created and saved to database. Because of that
 * this plugin will be called even if the group is not created due to some error like group with same userneme 
 * already exists in the database. If you set some property to the group like <i>good_students</i> in 
 * example above and group is successfully created this property will be saved to the database and you don't have to call
 * {@link save()} method later to store it. That is unlike {@link Psa_Plugin_After_Group_Create} plugin.
 * Also, group ID is unknown when this plugin is called and is set after the group is created.
 * 
 * @see Psa_Group
 * @see Psa_Group::save()
 * @see Psa_Group::__construct()
 * @see Psa_Plugin_Before_User_Create
 */
abstract class Psa_Plugin_Before_Group_Create extends Psa_Plugin_Model{
	
	/**
	 * This method will be called after new group is successfully created with {@link Psa_Group::save() save()} 
	 * method of the {@link Psa_Group} object.
	 * @param Psa_Group $group_object reference to the {@link Psa_Group} object whose {@link Psa_Group::save() save()} method is invoked
	 * @see Psa_Group::authorize()
	 */
	abstract protected function psa_main($group_object);
	
}

